home *** CD-ROM | disk | FTP | other *** search
/ The CICA Windows Explosion! / The CICA Windows Explosion! - Disc 2.iso / programr / ecjdll11.zip / ECJAPI.TXT < prev    next >
Text File  |  1993-09-09  |  6KB  |  174 lines
  1. Express Compression JPEG Application Program Interface (ECJAPI)
  2.  
  3. (c) 1993 Expressed Compression Laboratories
  4. ********************************************************************************
  5.  
  6. ECJ_Decode (1.x)
  7. --------------------------------------------------------------------------------
  8. #include "ecjapi.h"
  9.  
  10. HANDLE ECJ_Decode( lpstrfilename, wParam, lParam, lpfnECJ_CallBack )
  11.  
  12. LPSTR    lpstrFileName;        /* name of file to decode */
  13. WORD    wParam;            /* attributes */
  14. LONG    lParam;            /* reserved */
  15. ECJCB    lpfnECJ_CallBack;    /* call back routine */
  16.  
  17. ECJ_Decode decodes the specified JPEG file and returns a device independent
  18. bitmap (DIB).
  19.  
  20. Parameter     Description
  21. ---------------------------------------------------------------------------
  22. lpstrFileName     Points to a null-terminated string that names the JPEG
  23.          file to be decoded.
  24.  
  25. wParam         Specifies how to proceed with the decoding. This parameter
  26.          can be a combination of the following values.
  27.  
  28.          Value        Meaning
  29.          -------------- -------------------------------------------
  30.          ECJ_GRAY_ONLY    Create a gray only DIB.
  31.          ECJ_24_BITS    Create a 24 bit DIB.
  32.          ECJ_2_PASS    Use two-pass 24 to 8 bit colour quantisation.
  33.          ECJ_DITHER    Use FS dithering in two-pass color quantisation.
  34.          ECJ_HALF_SIZE    Shrink the dimensions of the picture by half.
  35.          ECJ_AUTO_HALF    Automatically shrink the dimensions of the
  36.                 picture by half when appropriate.
  37.  
  38.          ECJ_DITHER can only be used in conjunction with ECJ_2_PASS.
  39.          ECJ_GRAY_ONLY, ECJ_24_BITS and ECJ_2_PASS are mutually
  40.          exclusive. ECJ_AUTO_HALF takes precedence over ECJ_HALF_SIZE.
  41.          By default (with wParam = 0) ECJ_Decode creates an 8 bit DIB,
  42.          using single pass colour quantisation with ordered dithering
  43.          when appropriate.
  44.  
  45. lParam         Reserved.
  46.  
  47. lpfnECJ_CallBack Specifies the procedure-instance address of the callback
  48.          procedure. ECJ_Decode sends messages and periodically passes
  49.          control back to the client via the ECJ callback procedure.
  50.          Setting this parameter to NULL disables the callback
  51.          mechanism.
  52.          For more information see the description of the ECJ_CallBack
  53.          function.
  54.  
  55. Returns
  56. =======
  57. The return value is the handle to the DIB if the function is successful.
  58. Otherwise, it is NULL.
  59.  
  60. See Also
  61. ========
  62. ECJ_CallBack
  63.  
  64. ********************************************************************************
  65.  
  66. ECJ_DecodeMem (1.x)
  67. --------------------------------------------------------------------------------
  68. #include "ecjapi.h"
  69.  
  70. HANDLE ECJ_DecodeMem( hStream, dwStreamLen, wParam, lParam, lpfnECJ_CallBack )
  71.  
  72. HGLOBAL    hStream;        /* handle to bitstream in memory */
  73. DWORD    dwStreamLen;        /* size of bitstream in bytes */
  74. WORD    wParam;            /* attributes */
  75. LONG    lParam;            /* reserved */
  76. ECJCB    lpfnECJ_CallBack;    /* call back routine */
  77.  
  78. ECJ_DecodeMem decodes the specified JPEG file and returns a device independent
  79. bitmap (DIB). ECJ_DecodeMem is essentially the same as ECJ_Decode, except
  80. that instead of taking a filename it takes a memory object as input.
  81.  
  82. Parameter     Description
  83. ---------------------------------------------------------------------------
  84. hStream         Global handle to memory object containing bitstream
  85.          to be decoded.
  86.  
  87. dwStreamLen     Size of the bitstream in bytes.
  88.  
  89. See ECJ_Decode for explanations on the rest of the parameters.
  90.  
  91. ********************************************************************************
  92.  
  93. ECJ_CallBack (1.x)
  94. --------------------------------------------------------------------------------
  95. #include "ecjapi.h"
  96.  
  97. int CALLBACK ECJ_CallBack( mMsg, wParam, lParam )
  98.  
  99. WORD    mMsg;    /* message */
  100. WORD    wParam;    /* first message parameter */
  101. LONG    lParam;    /* second message parameter */
  102.  
  103. The ECJ_CallBack function is an application-defined callback function that
  104. processes messages sent by ECJ_Decode.
  105.  
  106. Parameter    Description
  107. --------------------------------------------------------------------------
  108. mMsg        Specifies the message.
  109.  
  110.         Message        Meaning
  111.         -----------------------------------------------------------
  112.         ECJ_RESOLUTION    Upon decoding the header of the image
  113.                 ECJ_Decode returns with the following
  114.                 information:
  115.  
  116.                 Parameter   Bits   Meaning
  117.                 -------------------------------------------
  118.                 lParam        0-15   Vertical dimension.
  119.                 lParam       15-32   Horizontal dimension.
  120.                 wParam        0-2    Video format.
  121.                            0 = Y;
  122.                            1 = YUV422;
  123.                            2 = YUV411;
  124.                            3 = YUV444;
  125.                 wParam         3     Picture shrunk by half.
  126.  
  127.         ECJ_PROGRESS    ECJ_Decode periodically returns control to
  128.                 the client with progress information:
  129.  
  130.                 wParam    Stage
  131.                 ------  ----------------------------------
  132.                 0    Pass 1
  133.                 1    Creating histogram
  134.                 2    Pass 2
  135.  
  136.                 For stages 0 and 2, lParam indicates percentage
  137.                 completion.
  138.  
  139.         ECJ_ERROR    An error has occured. wParam identifies the
  140.                 particular error.
  141.  
  142.                 wParam    Error
  143.                 ---------------------------------------------
  144.                  1    File is not JPEG.
  145.                  2    Can't open file.
  146.                  3    Unexpected EOF.
  147.                  4    Out of memory.
  148.                  5    Unrecognised video format.
  149.                  6    Unexpected scan component.
  150.                  7    Unexpected marker.
  151.                  8    Unexpected RST.
  152.                  9    Unsupported precision.
  153.                 10    User abort.
  154.  
  155. wParam        Message-dependent information.
  156.  
  157. lParam        More message-dependent information.
  158.  
  159. Returns
  160. =======
  161. To continue decoding a value of 0 shall be returned.
  162. A return value of -1 instructs ECJ_Decode to abort decoding immediately.
  163.  
  164. Comments
  165. ========
  166. The client does not have to process any of the messages. The simplest
  167. ECJ_CallBack function can simply return 0. A more well behaved application
  168. should take the opportunity to momentarily pass control back to Windows
  169. to achieve non-preemptive multitasking.
  170.  
  171. See Also
  172. ========
  173. ECJ_Decode
  174.